\name{StackAlgorithm}
\alias{StackAlgorithm}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Dot Stack Algorithm}
\description{
This is an implementation of an algorithm from Dang et al. (2010).  It is designed to alleviate overplotting by displacing dots that would overlap orthogonally to the plotting plane.  It is a nice way to view a univariate distribution, and has the potential to be extend to bivariate distributions using 3D graphics.  This is an internal function and is not meant to be called directly by the user.
}
\usage{
StackAlgorithm(data, h, interpolate = median)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{data}{\code{data} this is the actual data to run through the algorithm.  There should be no missing values (these are taken care of elsewhere prior to passing to \code{StackAlgorithm}
}
  \item{h}{\code{h} this sets the radii of the dots, and is used to determine whether or not they would overlap (be "neighbors").  For example, two data points 2 & 2.8 would not be neighbors if h = 0.25, but would be neighbors if h = 0.5 (because both dots would extend 0.25 from their center and thus overlap slightly).
}
  \item{interpolate}{\code{interpolate} this sets the function used to center each stack.  The default is \code{median} but anothe reasonable option would be \code{mean}.
}
}
\details{
If there are \eqn{n} elements in the data vector, this algorithm first creates an n x n logical matrix indicating whether the distance between each element and _every other_ one is less than \code{h * 2}.  This determines what each elements "neighbors" are.  Then it goes into a while loop, finds the value with the most neighbors, makes that the first stack, removes all elements associated with that stack, and then finds the next data value with the most neighbors, until the "neighbor" matrix is empty and all values belong to a stack (even if the stack only contains one value).  Then each stack is centered using the function specified in the \code{interpolate} argument.  This, ideally, makes each stack as representative as possible of its individual values.  Once the stacks are all created, the y coordinates for each point can be calculated using the \code{h} parameter so that each dot in a stack do not overlap vertically.  What is returned are the x and y coordinates corresponding to the initial data values.
}
\value{
A data frame of the x and y coordinates to plot.
}
\references{
  Tuan Nhon Dang, Leland Wilkinson, & Anushka Anand. Stacking Graphic Elements to Avoid Over-Plotting. (2010). \emph{IEEE TRANSACTIONS ON VISUALIZATION AND COMPUTER GRAPHICS}, 16:6, 1044--1052.

  Leland Wilkinson. (1999). Dot Plots. \emph{The American Statistician}, 53:3, 276--281.
}
\author{Joshua Wiley, \url{http://joshuawiley.com/}}
\note{These coordinates are not necessarily quite ready for plotting.  They are passed back and included in a broader DotStack object that has all the necessary information to create a plot.}

\seealso{\code{\link{StackedDots}} and \code{\link{link}}
}
\examples{
## None, see StackedDots.
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{dplot}
